home *** CD-ROM | disk | FTP | other *** search
/ Aminet 15 / Aminet 15 - Nov 1996.iso / Aminet / dev / gcc / ixemsdk.lha / man / cat3 / mpool.0 < prev    next >
Text File  |  1996-09-02  |  7KB  |  199 lines
  1.  
  2.  
  3.  
  4. MPOOL(3)                                                 MPOOL(3)
  5.  
  6.  
  7. NNAAMMEE
  8.        mpool - shared memory buffer pool
  9.  
  10. SSYYNNOOPPSSIISS
  11.        ##iinncclluuddee <<ddbb..hh>>
  12.        ##iinncclluuddee <<mmppooooll..hh>>
  13.  
  14.        MMPPOOOOLL **
  15.        mmppooooll__ooppeenn ((DDBBTT **kkeeyy,, iinntt ffdd,, ppggnnoo__tt ppaaggeessiizzee,, ppggnnoo__tt mmaaxxccaacchhee));;
  16.  
  17.        vvooiidd
  18.        mmppooooll__ffiilltteerr ((MMPPOOOOLL **mmpp,, vvooiidd ((**ppggiinn))((vvooiidd **,, ppggnnoo__tt,, vvooiidd **)),,
  19.             vvooiidd ((**ppggoouutt))((vvooiidd **,, ppggnnoo__tt,, vvooiidd **)),, vvooiidd **ppggccooookkiiee));;
  20.  
  21.        vvooiidd **
  22.        mmppooooll__nneeww ((MMPPOOOOLL **mmpp,, ppggnnoo__tt **ppggnnooaaddddrr));;
  23.  
  24.        vvooiidd **
  25.        mmppooooll__ggeett ((MMPPOOOOLL **mmpp,, ppggnnoo__tt ppggnnoo,, uu__iinntt ffllaaggss));;
  26.  
  27.        iinntt
  28.        mmppooooll__ppuutt ((MMPPOOOOLL **mmpp,, vvooiidd **ppggaaddddrr,, uu__iinntt ffllaaggss));;
  29.  
  30.        iinntt
  31.        mmppooooll__ssyynncc ((MMPPOOOOLL **mmpp));;
  32.  
  33.        iinntt
  34.        mmppooooll__cclloossee ((MMPPOOOOLL **mmpp));;
  35.  
  36. DDEESSCCRRIIPPTTIIOONN
  37.        _M_p_o_o_l  is  the  library interface intended to provide page
  38.        oriented buffer management of files.  The buffers  may  be
  39.        shared between processes.
  40.  
  41.        The  function  _m_p_o_o_l___o_p_e_n  initializes a memory pool.  The
  42.        _k_e_y argument is the byte string used to negotiate  between
  43.        multiple  processes wishing to share buffers.  If the file
  44.        buffers are mapped in shared memory, all  processes  using
  45.        the  same key will share the buffers.  If _k_e_y is NULL, the
  46.        buffers are mapped into private memory.  The  _f_d  argument
  47.        is  a  file descriptor for the underlying file, which must
  48.        be seekable.  If  _k_e_y  is  non-NULL  and  matches  a  file
  49.        already being mapped, the _f_d argument is ignored.
  50.  
  51.        The  _p_a_g_e_s_i_z_e argument is the size, in bytes, of the pages
  52.        into which the file is broken up.  The  _m_a_x_c_a_c_h_e  argument
  53.        is the maximum number of pages from the underlying file to
  54.        cache at any one time.  This value is not relative to  the
  55.        number of processes which share a file's buffers, but will
  56.        be the largest value specified by  any  of  the  processes
  57.        sharing the file.
  58.  
  59.        The  _m_p_o_o_l___f_i_l_t_e_r function is intended to make transparent
  60.        input and output processing of the pages possible.  If the
  61.  
  62.  
  63.  
  64.                            June 4, 1993                         1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. MPOOL(3)                                                 MPOOL(3)
  71.  
  72.  
  73.        _p_g_i_n  function  is  specified,  it  is  called each time a
  74.        buffer is read into the memory pool from the backing file.
  75.        If the _p_g_o_u_t function is specified, it is called each time
  76.        a buffer is written into the backing file.  Both functions
  77.        are  are called with the _p_g_c_o_o_k_i_e pointer, the page number
  78.        and a pointer to the page to being read or written.
  79.  
  80.        The function _m_p_o_o_l___n_e_w  takes  an  MPOOL  pointer  and  an
  81.        address  as  arguments.  If a new page can be allocated, a
  82.        pointer to the page is returned and  the  page  number  is
  83.        stored  into  the  _p_g_n_o_a_d_d_r  address.   Otherwise, NULL is
  84.        returned and errno is set.
  85.  
  86.        The function _m_p_o_o_l___g_e_t takes a MPOOL pointer  and  a  page
  87.        number as arguments.  If the page exists, a pointer to the
  88.        page is returned.  Otherwise, NULL is returned  and  errno
  89.        is set.  The flags parameter is not currently used.
  90.  
  91.        The  function  _m_p_o_o_l___p_u_t  unpins  the  page  referenced by
  92.        _p_g_a_d_d_r.  _P_g_a_d_d_r must be an address previously returned  by
  93.        _m_p_o_o_l___g_e_t  or  _m_p_o_o_l___n_e_w.   The flag value is specified by
  94.        _o_r'ing any of the following values:
  95.  
  96.        MPOOL_DIRTY
  97.               The page has been modified and needs to be  written
  98.               to the backing file.
  99.  
  100.        _M_p_o_o_l___p_u_t  returns 0 on success and -1 if an error occurs.
  101.  
  102.        The function _m_p_o_o_l___s_y_n_c writes all modified pages  associ-
  103.        ated   with   the  MPOOL  pointer  to  the  backing  file.
  104.        _M_p_o_o_l___s_y_n_c returns 0 on success and -1 if an error occurs.
  105.  
  106.        The  _m_p_o_o_l___c_l_o_s_e  function  free's up any allocated memory
  107.        associated with the memory pool  cookie.   Modified  pages
  108.        are  nnoott written to the backing file.  _M_p_o_o_l___c_l_o_s_e returns
  109.        0 on success and -1 if an error occurs.
  110.  
  111. EERRRROORRSS
  112.        The _m_p_o_o_l___o_p_e_n function may fail and set _e_r_r_n_o for any  of
  113.        the errors specified for the library routine _m_a_l_l_o_c(3).
  114.  
  115.        The _m_p_o_o_l___g_e_t function may fail and set _e_r_r_n_o for the fol-
  116.        lowing:
  117.  
  118.        [EINVAL]       The requested record doesn't exist.
  119.  
  120.        The _m_p_o_o_l___n_e_w and _m_p_o_o_l___g_e_t functions  may  fail  and  set
  121.        _e_r_r_n_o for any of the errors specified for the library rou-
  122.        tines _r_e_a_d(2)_, _w_r_i_t_e(2)_, and _m_a_l_l_o_c(3).
  123.  
  124.        The _m_p_o_o_l___s_y_n_c function may fail and set _e_r_r_n_o for any  of
  125.        the errors specified for the library routine _w_r_i_t_e(2).
  126.  
  127.  
  128.  
  129.  
  130.                            June 4, 1993                         2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. MPOOL(3)                                                 MPOOL(3)
  137.  
  138.  
  139.        The _m_p_o_o_l___c_l_o_s_e function may fail and set _e_r_r_n_o for any of
  140.        the errors specified for the library routine _f_r_e_e(3).
  141.  
  142. SSEEEE AALLSSOO
  143.        _d_b_o_p_e_n(3), _b_t_r_e_e(3), _h_a_s_h(3), _r_e_c_n_o(3)
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.                            June 4, 1993                         3
  197.  
  198.  
  199.